"""
coast - Plot continents, countries, shorelines, rivers, and borders.
"""

from collections.abc import Sequence
from typing import Literal

from pygmt.alias import Alias, AliasSystem
from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import (
    args_in_kwargs,
    build_arg_list,
    fmt_docstring,
    use_alias,
)
from pygmt.params import Box

__doctest_skip__ = ["coast"]


@fmt_docstring
@use_alias(A="area_thresh", C="lakes", E="dcw", L="map_scale", W="shorelines")
def coast(  # noqa: PLR0913
    self,
    resolution: Literal[
        "auto", "full", "high", "intermediate", "low", "crude", None
    ] = None,
    land: str | None = None,
    water: str | None = None,
    rivers: int | str | Sequence[int | str] | None = None,
    borders: int | str | Sequence[int | str] | None = None,
    box: Box | bool = False,
    projection: str | None = None,
    frame: str | Sequence[str] | bool = False,
    region: Sequence[float | str] | str | None = None,
    verbose: Literal["quiet", "error", "warning", "timing", "info", "compat", "debug"]
    | bool = False,
    panel: int | Sequence[int] | bool = False,
    transparency: float | None = None,
    perspective: float | Sequence[float] | str | bool = False,
    **kwargs,
):
    r"""
    Plot continents, countries, shorelines, rivers, and borders.

    Plots grayshaded, colored, or textured land masses [or water masses] on
    maps and [optionally] draws coastlines, rivers, and political
    boundaries. The data files come in 5 different resolutions: (**f**)ull,
    (**h**)igh, (**i**)ntermediate, (**l**)ow, and (**c**)rude. The full
    resolution files amount to more than 55 Mb of data and provide great
    detail; for maps of larger geographical extent it is more economical to
    use one of the other resolutions. If the user selects to paint the
    land areas and does not specify fill of water areas then the latter
    will be transparent (i.e., earlier graphics drawn in those areas will
    not be overwritten). Likewise, if the water areas are painted and no
    land fill is set then the land areas will be transparent.

    A map projection must be supplied.

    Full GMT docs at :gmt-docs:`coast.html`.

    $aliases
       - B = frame
       - D = resolution
       - F = box
       - G = land
       - I = rivers
       - J = projection
       - R = region
       - S = water
       - V = verbose
       - c = panel
       - p = perspective
       - t = transparency

    Parameters
    ----------
    $projection
    $region
        *Required if this is the first plot command.*
    $area_thresh
    $frame
    lakes : str or list
        *fill*\ [**+l**\|\ **+r**].
        Set the shade, color, or pattern for lakes and river-lakes. The
        default is the fill chosen for "wet" areas set by the ``water``
        parameter. Optionally, specify separate fills by appending
        **+l** for lakes or **+r** for river-lakes, and passing multiple
        strings in a list.
    resolution
        Select the resolution of the coastline dataset to use. The available resolutions
        from highest to lowest are: ``"full"``, ``"high"``, ``"intermediate"``,
        ``"low"``, and ``"crude"``, which drops by 80% between levels. Default is
        ``"auto"`` to automatically select the most suitable resolution given the chosen
        map scale.
    land
        Select filling of "dry" areas.
    water
        Select filling of "wet" areas.
    rivers
        Draw rivers. Specify the type of rivers to draw, and optionally append a pen
        attribute, in the format *river*\ /*pen* [Default pen is
        ``"0.25p,black,solid"``]. Pass a sequence of river types or *river*\ /*pen*
        strings to draw different river types with different pens.

        Choose from the following river types:

        - ``0``: Double-lined rivers (river-lakes)
        - ``1``: Permanent major rivers
        - ``2``: Additional major rivers
        - ``3``: Additional rivers
        - ``4``: Minor rivers
        - ``5``: Intermittent rivers - major
        - ``6``: Intermittent rivers - additional
        - ``7``: Intermittent rivers - minor
        - ``8``: Major canals
        - ``9``: Minor canals
        - ``10``: Irrigation canals

        Or choose from the following preconfigured river groups:

        - ``"a"``: All rivers and canals (types ``0`` - ``10``)
        - ``"A"``: Rivers and canals except river-lakes (types ``1`` - ``10``)
        - ``"r"``: Permanent rivers (types ``0`` - ``4``)
        - ``"R"``: Permanent rivers except river-lakes (types ``1`` - ``4``)
        - ``"i"``: Intermittent rivers (types ``5`` - ``7``)
        - ``"c"``: Canals (types ``8`` - ``10``)

        Example usage:

        - ``rivers=1``: Draw permanent major rivers with default pen.
        - ``rivers="1/0.5p,blue"``: Draw permanent major rivers with a 0.5-point blue
          pen.
        - ``rivers=["1/0.5p,blue", "5/0.3p,cyan,dashed"]``: Draw permanent major rivers
          with a 0.5-point blue pen and intermittent major rivers with a 0.3-point
          dashed cyan pen.
    map_scale : str
        [**g**\|\ **j**\|\ **J**\|\ **n**\|\ **x**]\ *refpoint*\ **+w**\ *length*.
        Draw a simple map scale centered on the reference point specified.
    box
        Draw a background box behind the map scale or rose. If set to ``True``, a simple
        rectangular box is drawn using :gmt-term:`MAP_FRAME_PEN`. To customize the box
        appearance, pass a :class:`pygmt.params.Box` object to control style, fill, pen,
        and other box properties.
    borders
        Draw political boundaries. Specify the type of boundary to draw, and optionally
        append a pen attribute, in the format *border*\ /*pen* [Default pen is
        ``"0.25p,black,solid"``]. Pass a sequence of border types or *border*\ /*pen*
        strings to draw different border types with different pens.

        Choose from the following border types:

        - ``1``: National boundaries
        - ``2``: State boundaries within the Americas
        - ``3``: Marine boundaries
        - ``"a"``: All boundaries (types ``1`` - ``3``)

        Example usage:

        - ``borders=1``: Draw national boundaries with default pen.
        - ``borders="1/0.5p,red"``: Draw national boundaries with a 0.5-point red pen.
        - ``borders=["1/0.5p,red", "2/0.3p,blue,dashed"]``: Draw national boundaries
          with a 0.5-point red pen and state boundaries with a 0.3-point dashed blue
          pen.
    shorelines : bool, int, str, or list
        [*level*\ /]\ *pen*.
        Draw shorelines [Default is no shorelines]. Append pen attributes
        [Default is ``"0.25p,black,solid"``] which apply to all four levels.
        To set the pen for a single level, pass a string with *level*\ /*pen*\ ,
        where level is 1-4 and represent coastline, lakeshore, island-in-lake shore,
        and lake-in-island-in-lake shore. Pass a list of *level*\ /*pen*
        strings to ``shorelines`` to set multiple levels. When specific
        level pens are set, those not listed will not be drawn.
    dcw : str or list
        *code1,code2,…*\ [**+g**\ *fill*\ ][**+p**\ *pen*\ ][**+z**].
        Select painting country polygons from the `Digital Chart of the World
        <https://en.wikipedia.org/wiki/Digital_Chart_of_the_World>`__.
        Append one or more comma-separated countries using the 2-letter
        `ISO 3166-1 alpha-2 convention
        <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`__.
        To select a state of a country (if available), append .\ *state*,
        (e.g, ``"US.TX"`` for Texas). To specify a whole continent, prepend **=**
        to any of the continent codes (e.g. ``"=EU"`` for Europe). Append
        **+p**\ *pen* to draw polygon outlines [Default is no outline] and
        **+g**\ *fill* to fill them [Default is no fill].
    $panel
    $perspective
    $transparency
    $verbose

    Example
    -------
    >>> import pygmt
    >>> # Create a new plot with pygmt.Figure()
    >>> fig = pygmt.Figure()
    >>> # Call the coast method for the plot
    >>> fig.coast(
    ...     # Set the projection to Mercator, and the plot width to 10 centimeters
    ...     projection="M10c",
    ...     # Set the region of the plot
    ...     region=[-10, 30, 30, 60],
    ...     # Set the frame of the plot, here annotations and major ticks
    ...     frame="a",
    ...     # Set the color of the land to "darkgreen"
    ...     land="darkgreen",
    ...     # Set the color of the water to "lightblue"
    ...     water="lightblue",
    ...     # Draw national borders with a 1-point black line
    ...     borders="1/1p,black",
    ... )
    >>> # Show the plot
    >>> fig.show()
    """
    self._activate_figure()

    if (
        kwargs.get("G", land) is None
        and kwargs.get("S", water) is None
        and kwargs.get("I", rivers) is None
        and kwargs.get("N", borders) is None
        and not args_in_kwargs(args=["C", "E", "Q", "W"], kwargs=kwargs)
    ):
        msg = (
            "At least one of the following parameters must be specified: "
            "land, water, rivers, borders, lakes, dcw, Q, or shorelines."
        )
        raise GMTInvalidInput(msg)

    aliasdict = AliasSystem(
        D=Alias(
            resolution,
            name="resolution",
            mapping={
                "auto": "a",
                "full": "f",
                "high": "h",
                "intermediate": "i",
                "low": "l",
                "crude": "c",
            },
        ),
        F=Alias(box, name="box"),
        G=Alias(land, name="land"),
        I=Alias(rivers, name="rivers"),
        N=Alias(borders, name="borders"),
        S=Alias(water, name="water"),
    ).add_common(
        B=frame,
        J=projection,
        R=region,
        V=verbose,
        c=panel,
        p=perspective,
        t=transparency,
    )
    aliasdict.merge(kwargs)

    with Session() as lib:
        lib.call_module(module="coast", args=build_arg_list(aliasdict))
